home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus Special 17 / AMIGAplus Sonderheft 17 (1999)(ICP)(DE)[!].iso / PD / Anwendungen / -DataTypes- / animation / animation.datatype.doc < prev    next >
Text File  |  1998-06-17  |  65KB  |  1,708 lines
  1. TABLE OF CONTENTS
  2.  
  3. animation.datatype/--datasheed--
  4. animation.datatype/--model--
  5. animation.datatype/ADTM_LOCATE
  6. animation.datatype/ADTM_PAUSE
  7. animation.datatype/ADTM_START
  8. animation.datatype/ADTM_STOP
  9. animation.datatype/DTM_COPY
  10. animation.datatype/DTM_FRAMEBOX
  11. animation.datatype/DTM_PRINT
  12. animation.datatype/DTM_PROCLAYOUT
  13. animation.datatype/DTM_REMOVEDTOBJECT
  14. animation.datatype/DTM_TRIGGER
  15. animation.datatype/DTM_WRITE
  16. animation.datatype/GM_GOACTIVE
  17. animation.datatype/GM_GOINACTIVE
  18. animation.datatype/GM_HANDLEINPUT
  19. animation.datatype/GM_HELPTEST
  20. animation.datatype/GM_HITTEST
  21. animation.datatype/GM_LAYOUT
  22. animation.datatype/GM_RENDER
  23. animation.datatype/MAIN
  24. animation.datatype/ObtainAnimationEngine
  25. animation.datatype/OM_DISPOSE
  26. animation.datatype/OM_GET
  27. animation.datatype/OM_NEW
  28. animation.datatype/OM_SET
  29. animation.datatype/OM_UPDATE
  30. animation.datatype/preferences
  31. animation.datatype/--datasheed--             animation.datatype/--datasheed--
  32.  
  33.     NAME
  34.         animation.datatype -- base datatype for animations
  35.  
  36.     SUPERCLASS
  37.         datatypesclass
  38.  
  39.     DESCRIPTION
  40.         The animation.datatype is the super-class for any animation related
  41.         classes.
  42.  
  43.         This class is responsible for creating the controls, scaling,
  44.         remapping and synchronization.
  45.  
  46.     METHODS
  47.         OM_NEW -- Create a new animation object. Passed to superclass, then
  48.             create internal resources, read preferences, then fall througth 
  49.             OM_SET.
  50.  
  51.         OM_GET -- Obtain the value of an attribute. Passed to superclass
  52.             if the attribute is not recognized by animation.datatype class.
  53.  
  54.         OM_SET -- Set the values of multiple attributes. Passed to
  55.             superclass first.
  56.  
  57.         OM_UPDATE -- Update the values of multiple attributes. Falls
  58.             througth to OM_SET.
  59.  
  60.         OM_NOTIFY -- Notify new attributes. Passed to superclass.
  61.  
  62.         OM_DISPOSE -- Dispose of a animation object. Passed to superclass
  63.             after animation.datatype instance has freed it's resources.
  64.  
  65.         GM_LAYOUT -- Layout the object and notify the application of the
  66.             title and size. Passed to superclass first.
  67.  
  68.         GM_HITTEST -- Determine if the object has been hit with the
  69.             mouse within the gadget domain rectange. Overrides the
  70.             superclass.
  71.  
  72.         GM_HELPTEST -- Determinate if the object has been hit by an help
  73.             test within the gadget help domain rectangle. Overrides the
  74.             superclass.
  75.  
  76.         GM_GOACTIVE -- Tell the object to go active. Overrides the
  77.             superclass.
  78.  
  79.         GM_HANDLEINPUT -- Handle input. Overrides the superclass.
  80.  
  81.         GM_GOINACTIVE -- Inactive the object. Overrides the superclass.
  82.  
  83.         GM_RENDER -- Cause the current frame to render.
  84.  
  85.         DTM_FRAMEBOX -- Obtain or set the display environment that the
  86.             animation requires. Passed to superclass first.
  87.             Currently, only "obtain" (e.g. FRAMEF_SPECIFY is NOT set)
  88.             is implemented, "set" might be implemented by a subclass...
  89.  
  90.         DTM_PROCLAYOUT -- Layout object on application process. See
  91.             GM_LAYOUT for functionality.
  92.  
  93.         DTM_REMOVEDTOBJECT -- Remove an object from the window/screen.
  94.             Passed to superclass after all.
  95.  
  96.         DTM_TRIGGER -- Cause an async event to occur.
  97.             Overrides the superclass.
  98.  
  99.         DTM_OBTAINDRAWINFO -- not implemented yet
  100.  
  101.         DTM_DRAW -- not implemented yet
  102.  
  103.         DTM_RELEASEDRAWINFO -- not implemented yet
  104.  
  105.         DTM_COPY -- Copy the current frame to the clipboard as an IFF ILBM
  106.             picture.
  107.             Overrides the superclass.
  108.  
  109.         DTM_WRITE -- Write the current or a specified frame to a file as an
  110.             IFF ILBM picture.
  111.             Overrides the superclass.
  112.  
  113.         DTM_PRINT -- Print the current or a specified frame.
  114.             Overrides the superclass.
  115.  
  116.         ADTM_LOADFRAME -- Load a frame of the animation.
  117.  
  118.         ADTM_UNLOADFRAME -- Deallocate any memory allocated by
  119.             ADTM_LOADFRAME.
  120.  
  121.         ADTM_START -- Start the animation.  This MUST be passed to the
  122.             super-class AFTER the sub-class has started.
  123.  
  124.         ADTM_PAUSE -- Pause the animation.  This MUST be passed to the
  125.             super-class BEFORE the sub-class pauses.
  126.  
  127.         ADTM_STOP -- Stop the animation.  This MUST be passed to the
  128.             super-class BEFORE the sub-class stops.
  129.  
  130.         ADTM_LOCATE -- Used to locate a frame of the animation.
  131.  
  132.         All other methods are passed to the superclass.
  133.  
  134.     ATTRIBUTES
  135.         OBP_Precison (ULONG) -- Precision to use when obtaining colors.
  136.             See the PRECISION_ defines in <graphics/view.h>.
  137.             Fixed to PRECISION_ICON (V40),
  138.             Defaults to PRECISION_IMAGE V41).
  139.  
  140.             Applicability is () (V40)
  141.             Applicability is (ISG) (V41)
  142.  
  143.         DTA_ControlPanel (BOOL) -- Determine whether the control
  144.             panel is shown.  Defaults to TRUE.
  145.             (It is currently not recommned to change this attribute while
  146.             the object is attached to a window/requester).
  147.             Note: Chaning this attribute affects also the height returned
  148.             by DTM_FRAMEBOX.
  149.  
  150.             Applicability is (I).
  151.             Applicability is (ISGU) (V41)
  152.  
  153.         DTA_Repeat (BOOL) -- Determine whether the animation
  154.             should repeat playing.  Defaults to FALSE.
  155.  
  156.             Applicability is (ISGU) (V41)
  157.  
  158.         DTA_Immediate (BOOL) -- Indicate whether the animation
  159.             should immediately begin playing.  Defaults to
  160.             FALSE.
  161.  
  162.             Applicability is (I).
  163.             Applicability is (ISGU) (V41)
  164.  
  165.         ADTA_ModeID (ULONG) -- Set and get the graphic mode id of the
  166.             picture. The mode id set here will be checked by BestModeIDA
  167.             based on width/height/depth info of the animation.
  168.             Defaults to 0.
  169.  
  170.             Applicability is (ISG).
  171.  
  172.         ADTA_KeyFrame (struct BitMap *) -- Pointer to the key
  173.             frame.
  174.  
  175.             This bitmap should be allocated using AllocBitMap because this
  176.             is the only way to force GetBitMapAttr and other functions to
  177.             return correct attributary flags.
  178.  
  179.             This bitmap will be used for internal calculations and
  180.             assumtions about bitmap data layout; the bitmaps got from
  181.             ADTM_LOADFRAME have the same size and layout, but GetBitMapAttr
  182.             may return wrong values for these bitmaps!
  183.  
  184.             Note that this bitmap type may change if someone says the object
  185.             in which environment the object will be embedded in
  186.             (DTM_FRAMEBOX). In this case a subclass may change the output
  187.             format (preserving only ADTA_Width and ADTA_Height).
  188.  
  189.             Applicability is (ISG).
  190.  
  191.         ADTA_ColorRegisters (struct ColorRegister *) -- Color table.
  192.  
  193.             Applicability is (G).
  194.  
  195.         ADTA_CRegs (ULONG *) -- Color table to use with SetRGB32CM().
  196.  
  197.             Applicability is (G).
  198.  
  199.         ADTA_GRegs (ULONG *) -- Color table (like ADTA_CRegs, but contains
  200.             color values of allocated (shared) pens).
  201.  
  202.             Applicability is (G).
  203.  
  204.         ADTA_ColorTable (ULONG *) -- PRIVTAE
  205.         ADTA_ColorTable2 (ULONG *) -- PRIVATE
  206.  
  207.             Applicability is (G).
  208.  
  209.         ADTA_Allocated (ULONG) --  Number of shared colors allocated.
  210.  
  211.              Applicability is (G).
  212.  
  213.         ADTA_NumColors (WORD) -- Number of colors used by the picture.
  214.             (May be 0 in the case of a truecolor animatoin without a
  215.             palette).
  216.  
  217.             Applicability is (ISG).
  218.  
  219.         ADTA_NumAlloc (WORD) -- Number of colors allocated by the picture.
  220.  
  221.             Applicability is (G).
  222.  
  223.         ADTA_Remap (BOOL) -- Indicate whether the animation should be
  224.             remapped or not.
  225.             Defaults to TRUE.
  226.  
  227.             Applicability is (IS).
  228.             Applicability is (ISG) (V41).
  229.  
  230.         ADTA_Screen (struct Screen *) -- Screen to remap to
  231.  
  232.             Applicability is (IS) (V41).
  233.  
  234.         ADTA_NumSparse (UWORD) -- Number of colors used for sparse remapping
  235.  
  236.             Applicability is (IS) (V41).
  237.  
  238.         ADTA_SparseTable (UBYTE *) -- Pointer to a table of pen numbers
  239.             indicating which colors should be used when remapping the image.
  240.             This array must contain as many entries as there
  241.             are colors specified with ADTA_NumSparse
  242.  
  243.             Applicability is (IS) (V41).
  244.  
  245.         ADTA_Width (ULONG) -- Width of a frame in pixels.
  246.  
  247.             Applicability is (ISG).
  248.  
  249.         ADTA_Height (ULONG) -- Height of a frame in pixels.
  250.  
  251.             Applicability is (ISG).
  252.  
  253.         ADTA_Depth (ULONG) -- Depth of the frame.
  254.  
  255.             Applicability is (ISG).
  256.  
  257.         ADTA_Frames (ULONG) -- Number of frames in animation.
  258.             Defaults to 0,
  259.             setting this attribute also affects ADTA_FrameIncrement
  260.             (e.g. set it's to 10 except if ADTA_Frames < 50, then
  261.             ADTA_FrameIncrement = ADTA_Frames / 5).
  262.  
  263.             Applicability is (ISG).
  264.  
  265.         ADTA_Frame (ULONG) -- Currect frame
  266.             Setting of this attribute causes an ADTM_LOCATE !
  267.  
  268.             Applicability is (G).
  269.             Applicability is (SGU) (V41)
  270.  
  271.         ADTA_FramesPerSecond (ULONG) -- Number of frames per
  272.             second to play.
  273.             V40 limits this to 60 fps, V41 increases the limit up to
  274.             1200 fps (max. realtime.library resolution).
  275.             (Setting this tag may also affect the default value for
  276.             ADTA_NumPrefetchFrames.)
  277.             Defaults to 10.
  278.  
  279.             Applicability is (ISG).
  280.  
  281.         ADTA_TicksPerFrame (ULONG) -- realtime.library ticks per frame
  282.             Defaults to TICK_FREQ / 10 = 120
  283.             (Setting this tag may also affect the default value for
  284.             ADTA_NumPrefetchFrames.)
  285.  
  286.             Applicability is (ISG) (V41).
  287.  
  288.         ADTA_CurrFramesPerSecond (ULONG) -- current frames per second rate
  289.             The playback rate and sound playback speed are recalculated
  290.             to match this value.
  291.             If ADTA_AdaptiveFPS is TRUE, this value is recalculated to
  292.             allow the maximum available playback speed on the hardware
  293.             (limmitted by ADTA_FramesPerSecond)
  294.  
  295.             Applicability is (ISGU) (V41).
  296.  
  297.         ADTA_CurrTicksPerSecond (ULONG) -- current ticks per second rate
  298.             The playback rate and sound playback speed are recalculated
  299.             to match this value.
  300.             If ADTA_AdaptiveFPS is TRUE, this value is recalculated to
  301.             allow the maximum available playback speed on the hardware
  302.             (limmitted by ADTA_TicksPerSecond)
  303.  
  304.             Applicability is (ISGU) (V41).
  305.  
  306.         ADTA_FrameIncrement (ULONG) -- Amount to change frame by when fast
  307.             forwarding or rewinding.
  308.             Defaults to 10
  309.  
  310.             Applicability is (G).
  311.             Applicability is (SGU) (V41)
  312.  
  313.         ADTA_BitMapHeader (struct BitMapHeader *) -- Set and get the
  314.             base information for the animation.  BitMapHeader is defined in
  315.             <datatypes/pictureclass.h>
  316.             Setting this tag causes the given struct BitMapHeader to be copie
  317. d
  318.             into the object.
  319.             This also causes ADTA_Width, ADTA_Height, ADTA_Depth to be set.
  320.  
  321.             Applicability is (G).
  322.             Applicability is (ISG) (V41)
  323.  
  324.         ADTA_Sample (BYTE *) -- Pointer to sample data.
  325.  
  326.             Applicability is (ISG).
  327.  
  328.         ADTA_SampleLength (ULONG) -- Length of sample data.
  329.  
  330.             Applicability is (ISG).
  331.  
  332.         ADTA_Period (ULONG) -- Period to play back sample at.
  333.             Defaults to 360.
  334.  
  335.             Applicability is (ISG).
  336.  
  337.         ADTA_Volume (ULONG) -- Volume to play back sample at.
  338.             Defaults to 64.
  339.  
  340.             Applicability is (ISG).
  341.             Applicability is (ISGU) (V41).
  342.  
  343.         ADTA_Cyles (ULONG) -- Cycles to play.
  344.             Defaults to 1.
  345.  
  346.             Applicability is (G).
  347.  
  348.         ADTA_AdaptiveFPS (BOOL) -- If TRUE, the playback rate is limitted
  349.             to the maximum reachable playback rate without frame skipping.
  350.  
  351.             Defaults to TRUE, but maybe changed using the prefs-file (V41).
  352.  
  353.         ADTA_SmartSkip (BOOL) -- If TRUE, some frames are skipped based
  354.             on internal statistics to keep playback and sound in sync.
  355.  
  356.             Defaults to FALSE, but maybe changed using the prefs-file (V41).
  357.  
  358.         ADTA_NumPrefetchFrames (ULONG) -- Number of frames to be
  359.             prefetched by the loading process.
  360.             Must be at least 5, lower values are bumped to 5.
  361.  
  362.             Defaults to 1/2 fps value unless set explicietly by OM_SET or
  363.             using the prefs-file (V41).
  364.  
  365.         ADTA_OvertakeScreem (BOOL) -- Overtake screen palette when not
  366.             remapping.
  367.             Applications should set this explicitly to FALSE if they don't
  368.             want to be affected by this datatype.
  369.  
  370.             Defaults to TRUE, but maybe changed using the prefs-file (V41).
  371.  
  372.     BUGS
  373.         Horrors. This version (V41.6) suffers under the 1001
  374.         nightmare bugs problem:
  375.  
  376.         After all, I think the current version has the following bugs:
  377.  
  378.         - The CPU blitter support is currently broken. Instead of doing
  379.           a small speed comparisation between OS blitter and CPU blitter
  380.           the CPU blitter is enabled on a mc68030 per default if remapping
  381.           is required.
  382.           Who likes to use the CPU blitter evertimes (if the subclass decoder
  383.           creates planar output), set explicitly the CPUBLITTER switch in the
  384.           prefs file, to turn off the CPU blitter evertimes is the OSBLITTER
  385.           option.
  386.  
  387.         - timing may be slightly inaccurate. On a rate of 10 fps, this
  388.           isn't bad, but using fps >= 1 or lower (e.g.
  389.           ADTA_TicksPerFrame > 1200), you may see the problem.
  390.  
  391.         - ADTA_OvertakeScreen does not work correctly. Currently it is
  392.           always set to TRUE.
  393.  
  394.         - Internal statistics (for ADTA_AdaptiveFPS, ADTA_SmartSkip etc.)
  395.           are working now, but the wheighting of loading and display time
  396.           can be made better.
  397.  
  398.         - ADTA_SmartSkip code has been disabled.
  399.  
  400.         - CyberGFX code has been disabled because it isn't tested yet.
  401.  
  402.         - Incompatible with the current V41.11 cgxsystem.library
  403.           PLANES2FAST option, because the GetBitMapAttr function does not
  404.           BMF_STANDARD flag and then animation.datatype treats the bitmaps 
  405.           as non-planar, which cannot be remapped.
  406.  
  407.         - planar bitmaps with depth > 8 are not supported yet, sorry.
  408.  
  409.         - tapedeck.gadget handling is very tricky, and may have some
  410.           problems.
  411.  
  412.         - On a highly loaded system the animation playback can't be
  413.           stopped on the fly (IPC communication has problems with this).
  414.           This happens often when DTA_Repeat is set, and the
  415.           ADTM_STOP, ADTM_START cycle occurs to rewind the animation.
  416.  
  417.         - IPC communication is __VERY__ complex. We have 5 (!) threads
  418.           to be controlled and sync'ed:
  419.           - loader process
  420.           - display and control process
  421.           - input.device
  422.           - application process
  423.           - realtime.library player interrupt
  424.  
  425.           Don't expect that all works fine here...
  426.  
  427.         - DTA_Repeat == TRUE does not work with anims with less than 3
  428.           frames, because the first frame is skipped.
  429.           This causes problems with (for example) 2 frame gif animations.
  430.  
  431.         - ADTA_NumSpase and ADTA_SparseTable does not work yet, sorry.
  432.  
  433.     TODO
  434.         - In HAM-mode, a box of color 0 should be drawn around the object
  435.           to avoid some ugly HAM-effects when the background of the parent
  436.           window is not 0.
  437.           (Idea was taken from "cdgsxl").
  438.  
  439.         - Remapping code HAM -> 24-bit
  440.  
  441.         - Remapping code EHB -> Other amiga modes
  442.  
  443.         - Support for non-planar bitmap types (chunkypixel etc.).
  444.  
  445.         - Support for 12/15/16/18/21/24-bit planar bitmaps (direct-RGB 
  446.           coded).
  447.  
  448.         - Get some more info about the mysterious tapedeck.gadget.
  449.  
  450.         - The CBM OS 3.1 tapedeck.gadget is limited to a height of 16
  451.           pixels. If I have time, I can write my own version WITHOUT this
  452.           limitation...
  453.  
  454.     HISTORY
  455.         V41.1
  456.           - Initial release to DataTypes Mailinglist
  457.  
  458.         V41.2
  459.           - Recompiled with SAS/C 6.58; this may fix mc68060 related
  460.             problems.
  461.  
  462.           - Now the tapedeck update is slightly better because a "magic"
  463.             update (using a gpr_Redraw of 100 instead of GREDRAW_UPDATE)
  464.             is used.
  465.             Thanks to Heinz Wrobel.
  466.  
  467.           - Fixed the bug that after resizing the parent window the
  468.             height of the playback area was not restored. 
  469.             Fixed.
  470.  
  471.           - If the display screen is not visible, the old V40.6 turns
  472.             of the bitmap display (using the VP_HIDE flags).
  473.             Now V41 does the same.
  474.             Thanks to Heinz Wrobel for explaining this. Because this
  475.             may be a hack (not documented by the OS docs), this
  476.             feature is turned off if the NOHACKS switch is set in the
  477.             prefs file.
  478.  
  479.           - Fixed internal statistics (used for adaptive playback rate
  480.             calculations). Now the datatype tracks time-to-unload-a-frame,
  481.             too.
  482.  
  483.           - Fixed a problem with adaptive playback rate selection
  484.             and dynamic timing. The new model seems to run more smoothly,
  485.             but this is still a weak point.
  486.  
  487.           - Recompiled the project with DATA=FARONLY. I think that this
  488.             should fix some problems.
  489.             Thanks to Steve Krueger (sekruege@nando.net) for answering
  490.             some questions.
  491.  
  492.           - Moved OS vs. CPU blitter selection code from GM_LAYOUT
  493.             to the first GM_RENDER after GM_LAYOUT. This should be more
  494.             reliable, and speeds up the initial window layout a little
  495.             bit.
  496.  
  497.           - Seems that there is a bug in the CPU blitter (selection) code.
  498.             For now I wrote a small workaround; the CPU blitter is
  499.             enabled per default on a mc68030 if ADTA_Remap is set to TRUE
  500.             (assuming that the cpu blitter function running on a mc68030 is
  501.             a little bit faster than the OS blitter).
  502.  
  503.           - Updated the autodocs.
  504.  
  505.           - OM_DISPOSE now preserves result2 (e.g. IoErr() result)
  506.             explicitly.
  507.  
  508.           - OM_DISPOSE now sets the embedded sound.datatype object's
  509.             SDTA_Sample to NULL. This fixes possibly problems if a
  510.             sound.datatype clone tries to FreeVec' the sample...
  511.  
  512.           - Removed code from OM_DISPOSE which is executed in
  513.             DTM_REMOVEDTOBJECT (e.g. freeing of pens and tmp. bitmaps).
  514.  
  515.           - Now OM_GET ADTA_Sample, ADTA_SampleLength, ADTA_Period, 
  516.             ADTA_Volume and ADTA_Cycles are got from the current frame.
  517.             This feature should work now.
  518.  
  519.           - Implemeted OM_GET ADTA_DestFrame (alias PDTA_DestBitMap). Note 
  520.             that accessing this bitmap is ONLY safe when the object does not
  521.             do any playback; the same rule must be respected for
  522.             ADTA_Sample, ADTA_SampleLength and ADTA_Period.
  523.  
  524.           - Added CBM cdxl.datatype compatibility hack (I'm __very__ angry
  525.             about this problem because it took a long time to find the
  526.             problem). It seems that CBM's cdxl.datatype requires that it's
  527.             instance data are on long-word boundary because the data starts
  528.             with a FileInfoBlock.
  529.             Don't rely on this feature !!!
  530.  
  531.           - If the object setup (OM_NEW) failed in a sub-process, the error
  532.             code is now passed to the parent process and there stored
  533.             in Result2. This includes realtime.library errors, too.
  534.  
  535.           - Now uses AllocPooled and an internal memory management to
  536.             avoid memory allocations whereever and whenever possible.
  537.  
  538.           - Internal divisions are now rounded when usefull.
  539.  
  540.           - Child processes are now starting in sequence instead of a
  541.             parallel setup. This is only for testing; later I'll write the
  542.             parallel setup again.
  543.  
  544.           - Fixed the bug that GM_RENDER with GREDRAW_REDRAW didn't work 
  545.             properly if the parents box was only changed of one of X- OR
  546.             the Y-axis (e.g. EraseRect wasn't done in this case).
  547.  
  548.           - Fixed the bug that tapedeck.gadget was drawn even if the
  549.             DTA_Domain height was below GA_Height (tapedeck.gadget can't
  550.             clip in Y-direction).
  551.             This fixes visual problems with embed.datatype.
  552.             The check is also made in GM_HITTEST, GM_HELPTEST and
  553.             GM_GOACTIVE.
  554.  
  555.           - If DTA_ControlPanel is FALSE and the mouse SELECTUP starts the
  556.             playback, a following mouse SELECTUP now pauses the playback.
  557.  
  558.           - The stack swapping code now allocates it's memory without
  559.             MEMF_CLEAR, which should result in a small speedup when doing
  560.             things.
  561.  
  562.           - The library base now has 16 reserved lvo entries after
  563.             ObtainEngine which returns all 0 for now.
  564.             All these entries are reserved and private for now.
  565.  
  566.           - DTM_REMOVEDTOBJECT now passes the msg to superclass after doing
  567.             it's work. This fixes problems with some datatypesclass
  568.             internals.
  569.             Fixed.
  570.  
  571.           - DTM_FRAMEBOX now passes the msg to superclass before doing
  572.             it's work. Now datatypesclass can release the input clipboard
  573.             which avoids that the clipboard unit is locked while the object
  574.             exists.
  575.             Fixed.
  576.  
  577.           - Fixed the bug that setting ADTA_ModeID to INVALID_ID caused
  578.             havoc in the object (remapping code got turned off, the
  579.             palette of a public screen was changed etc.).
  580.             Now a ADTA_ModeID of INVALID_ID is treated as a 0UL mode id.
  581.             Thanks to Francis Labrie (fb691875@er.uqam.ca) for reporting
  582.             the bug.
  583.             Fixed.
  584.  
  585.           - Fixed the bug that when the CPU blitter draws the display, a
  586.             GM_RENDER showed the first frame. Now a GM_RENDER and other
  587.             methods sync's the ADTA_DestFrame bitmap correctly (e.g. copy
  588.             the (remapped) src bitmap) into ADTA_DestFrame) before using it.
  589.             Fixed.
  590.  
  591.           - Changed some internals that moving the tapedeck.gadget's slider
  592.             causes less overhead when loading single frames.
  593.  
  594.           - Now the animation.datatype instance data contents are on a
  595.             long-word aligned boundary, which should speed up some things.
  596.             (Tested only with Kick 3.0 yet).
  597.  
  598.           - Fixed a bug in the ADTA_OvertakeScreen code that caused that
  599.             the last color in a palette change was set to black instead
  600.             of the wanted color.
  601.             Fixed.
  602.  
  603.         V41.3
  604.           INTERNAL RELEASE
  605.  
  606.           - Fixed the bug that a non-planar (chunky) bitmaps wasn't passed
  607.             througth.
  608.  
  609.           - Improved internal GetPictureCopy (which is used to create the
  610.             temp. object for DTM_COPY, DTM_WRITE, DTM_PRINT):
  611.             - It now uses the key bitmap as a friend bitmap parameter.
  612.               This may fix problems when processing non-planar bitmaps.
  613.  
  614.               WARNING: This may result in large problems if a < V43
  615.               picture.datatype is used in a GFX-card environment (CyberGFX,
  616.               Picasso 96 etc.).
  617.  
  618.             - It now does not attempt to copy a colormap if is
  619.               ADTA_NumColors == 0 (added this check to avoid some
  620.               unneccesary memory copies which result all in a big NOP is
  621.               this case).
  622.  
  623.           - Reduced the memory usage if non-planar input bitmaps are used
  624.             by the subclass (the temporary bitmaps used for remapping etc.
  625.             are not allocated (because they were not used...)).
  626.  
  627.           - Tests have shown that the PLANES2FAST option of
  628.             cgxsystem.library V41.11 is incompatible with animation.datatype
  629.             because the GetBitMapAttr function does not set BMF_STANDARD for
  630.             these bitmaps even if they are planar.
  631.             This causes that the bitmaps are treated as chunkypixel ones
  632.             (where the remapping code can't touch them).
  633.             Cannot be fixed yet.
  634.  
  635.         V41.4
  636.           Version for the "Compuler 97'" fair in Colone/Germany
  637.  
  638.           - Replaced the custom stack swapping code by my "standard" module
  639.  
  640.           - Fixed the bug that a failed palette allocation (e.g. setting of
  641.             ADTA_NumColors) return random values for the ADTA_CRegs,
  642.             ADTA_ColorRegisters etc. attributes if it was set more than once
  643.             in objects lifetime and the allocation failes.
  644.             The attributes now return correctly NULL in this case.
  645.             Fixed.
  646.  
  647.           - If ADTA_NumColors is set to 0, now ADTA_CRegs,
  648.             ADTA_ColorRegisters, ADTA_GRegs etc. return a NULL pointer
  649.             instead of returning random values.
  650.  
  651.           - Minor code cleaup.
  652.  
  653.           - Oops, the last distribution missed the
  654.             "datatypes/animationclassext.h" include file.
  655.  
  656.         V41.5
  657.           - Fixed a bug that some things (like internal CopyBitMapPlanar)
  658.             only worked if the object has been added to the display.
  659.             Fixed.
  660.  
  661.           - Fixed the bug that the alf_Duration field wasn't respected for
  662.             ADTM_LOCATE and the first frames played back by ADTM_START.
  663.             Fixed.
  664.  
  665.           - Enabled the remapping code for 8-bit chunkypixel bitmaps.
  666.             This also fixes the problem with CyberGFX that planar bitmaps
  667.             in are not detected in CGFX PLANES2FAST mode (but there a still
  668.             a couple of bugs...).
  669.             Should work now...
  670.  
  671.           - Fixed the bug (in theory, but it does never happen) that the
  672.             load process did not clear some internal flags on exit
  673.             which may cause deadlocks if an application fires ADTM_START
  674.             after the object has been removed from display (which
  675.             is illegal, but...).
  676.             Fixed.
  677.  
  678.           - Major changes in the IPC communication and timing parts.
  679.             Main reason was to reduce the delay gap caused by a repeat
  680.             rewind (if DTA_Repeat is TRUE).
  681.  
  682.           - OM_GET ADTA_Sample, ADTA_SampleLength, ADTA_Period
  683.             refers to the current frame, if there is no current frame
  684.             the attributes refers to the first frame.
  685.             The "feature" introduced in V41.2 to get the "current"
  686.             values from the sound.datatype object wasn't very usefull
  687.             because CBM's sound.datatype did not support OM_GET for these
  688.             attributes.
  689.  
  690.         V41.6
  691.           - Fixed the bug that STM_LOCATE did not work properly. The
  692.             DTA_TriggerMethods info says that "Locate" is
  693.             (STM_LOCATE | STMD_ULONG), but the trigger command dispatcher
  694.             checked the old STM_LOCATE (without the STMD_#? flag).
  695.             Now the trigger command dispatcher masks the trigger method
  696.             using ((trigger_method) & ~STMF_DATA_MASK) to get rid of the
  697.             STMD_#? info...
  698.             Fixed.
  699.  
  700.           - Added SHARECHIP / NOSHARECHIP options. Before V41.6, the
  701.             animation.datatype tests incoming planar bitmaps of they lie in
  702.             chipmem can can be passed to BltBitMapRastport directly without
  703.             using a copy to a chipmem buffer.
  704.             Now this test is avoided unless the SHARECHIP option is on
  705.             again. The prefs docs about this option explains why this may be
  706.             good in certain cases...
  707.  
  708.           - tapedeck.gadget's special GM_RENDER mode 100 (GREDRAW_SLIDER, e.g
  709. .
  710.             only update embedded slider) is never more treated as an hack.
  711.  
  712.           - Small speedup because tapedeck's rastport using for
  713.             GM_RENDER/GREDRAW_SLIDER is now set up at GM_LAYOUT time
  714.             instead of a once-pre-draw setup.
  715.  
  716.           - The 8-bit-chunkypixel remapping code has been re-written.
  717.             It now remaps RPL8 / remap / WPL8 instead using a RPA8 / remap /
  718.             WPA8 cycle (the line-by-line should be more cache-friendly and
  719.             therefore faster...).
  720.             The memory needed for this remapping is also reduced
  721.             significantly...
  722.  
  723.           - The 8-bit-chunkypixel remapping code never more checks
  724.             for the return codes of RPL8/RPA8 nor WPL8/WPA8.
  725.             It seems that the GFX-Card driver software sometimes returns
  726.             rubbish here...
  727.             Should fix some reported blank displays...
  728.  
  729.           - Added support for FIF_ABILITIES (bit 31, (0x80000000UL)).
  730.             This flag indicates that animation.datatype supports the
  731.             FIF_#? flags. "GMultiView" for example now looks on this
  732.             flag and is able to show a HAM/EHB animation on a public 
  733.             screen if we support the remapping for it.
  734.  
  735.           - Fixed the bug that DTM_TRIGGER did not send
  736.             DTERROR_COULDNT_SEND_MESSAGE in the case of no receiver.
  737.             Fixed.
  738.  
  739.           - Now SAS/C's build-in math functions are used instead of
  740.             the C macros...
  741.  
  742.           - Changed the default value of ADTA_NumPrefetchFrames.
  743.             Instead of 10 frames to prefetch now (1/2 fps) number of
  744.             frames will be pre-fetched during loading.
  745.             Setting ADTA_NumPrefetchFrames explicitly by OM_SET or
  746.             by the prefs-file will turn this automatic selection off
  747.             again...
  748.             This may give a more reasonable default value for
  749.             mpegvideo.datatype's NOLOADALL mode...
  750.  
  751.           - Fixed the bug in OM_NEW that if realtime.libary/CreatePlayerA
  752.             failed with an PLAYER_ErrorCode error not of RTE_NOMEMORY or
  753.             RTE_NOCONDUCTOR Result2 (IoErr) was set to 0.
  754.             Due lack of a good dos.library error code if've set the
  755.             code to 1234L for now.
  756.             Fixed.
  757.  
  758.           - Small modifications in the code which may caused problems with
  759.             animations with more than 16384 pixel width and/or height.
  760.             These dimensions are currently therorectical, but:
  761.             Fixed.
  762.  
  763.           - DTM_REMOVEOBJECT now causes that all queuing frames in the
  764.             display queue are disposed (e.g. moved to the dispose queue).
  765.             This avoids the bug that removing the object from a window
  766.             and re-attaching it again may cause that next play cycle will
  767.             display these frames first.
  768.             Fixed.
  769.  
  770.           - The priority of the display and load processes are now set up
  771.             based on the parent process priority (e.g. the process which
  772.             executes OM_NEW).
  773.             The display process gets parent process priority, the load
  774.             process gets "parent priority - 1".
  775.             This allows to run the playback at higher priorities.
  776.  
  777.           - { GA_Immediate, TRUE } is not set any more for the
  778.             tapedeck.gadget. This seems to fix some problems with input
  779.             processing from tapedeck.gadgets.
  780.  
  781.           - Fixed the bug that tapedeck.gadget's TDECK_CurrentFrame attribute
  782.             wasn't updated if DTA_ControlPanel is set to TRUE.
  783.             Fixed.
  784.  
  785.           - ADTM_START now clears the load queue explicitly if the first
  786.             frame in the queue matches not the given "asa_Frame".
  787.  
  788.     SEE ALSO
  789.         mpegsystem.datatype, mpegvideo.datatype,
  790.         picmovie.datatype,
  791.         cdxl.datatype. avi.datatype, quicktime.datatype,
  792.         moviesetter.datatype,
  793.         film.datatype
  794.  
  795.     THANKS TO
  796.         David Junod for the design and the first implemenation,
  797.         Olaf Barthel for his great help,
  798.         Heinz Wrobel for explaining some things.
  799.         Frank Mariak for his CPU blitter replacement and CyberGFX support,
  800.         Niels Froeling for the planar remapping code,
  801.         and the people of the DataTypes Mailing list for testing and their
  802.         help
  803.  
  804. animation.datatype/--model--                     animation.datatype/--model--
  805.  
  806.     MODEL
  807.         <The following has not been finished yet. It's only a first, small,
  808.         poorly, genernal overview about the used model>
  809.  
  810.         The following short text should describe how the animation.datatype
  811.         works (in general):
  812.  
  813.         The animation.datatype is split up in four parts:
  814.          1. the decoder (the subclass which sits on animation.datatype)
  815.          2. the loading process
  816.          3. the display and control process
  817.          4. a realtime.library Player (timing interrupt)
  818.          5. a control process (application process, or input.device)
  819.  
  820.       1. The Decoder
  821.          The decoder part belongs completely to the subclass (sitting on
  822.          animation.datatype). animation.datatype communicates through
  823.          methods (ADTM_START, ADTM_PAUSE, ADTM_STOP, ADTM_LOCATE,
  824.          ADTM_LOADFRAME and ADTM_UNLOADFRANE) with the subclass.
  825.          Mainly, ADTM_LOADFRAME and ADTM_UNLOADFRAME are used to load/unload
  826.          a frame from the subclass.
  827.  
  828.       2. The Loading Process
  829.          The loading process has a simple task: Load as much frames as
  830.          possible and store the frames into a "frame queue".
  831.          The idea is that the loading process (which runns at a lower
  832.          priority than the display process) consumes all CPU time which is
  833.          not used by the display process.
  834.  
  835.          The load process is controlled by the display and the control
  836.          process (the application., for example), which can set one of
  837.          the following modes for the load process:
  838.          a) preload: Load the next 10 (can be changed by the prefs-file)
  839.                      frames, then stop.
  840.          b) play:    Fill the "frame queue" until it is full (e.g. until
  841.                      it reaches 10 frames or more).
  842.          c) stop:    Stop loading and preloading
  843.          d) flush:   flush frame queue
  844.  
  845.       3. The Display Process
  846.          The display process is responsible for remapping and displaying
  847.          of frames during playback. If signalled by the realtime.library
  848.          Player, the display process gets the first frame from the frame
  849.          queue, remapps it (if neccesary) and displays it. If a sample
  850.          is attached to the frame, the sample is fed to the embedded
  851.          sound.datatype object.
  852.  
  853.       4. The realtime.library Player (Timing Interupt)
  854.          The player has the job to decrase a counter each 1/1200 sec.
  855.          If the counter reaches 0, it is time to display the next frame,
  856.          and the interrupt fires a signal to the display process to
  857.          trigger the display of the frame.
  858.  
  859.       5. The Control Process
  860.          There is no fixed control process. But the application is allowed
  861.          to send ADTM_START, ADTM_PAUSE, ADTM_STOP and ADTM_LOCATE to
  862.          trigger a playback, pause or stop it - or locate a single frame.
  863.          The same counts for the user, who plays with the embedded
  864.          tapedeck.gadget.
  865.  
  866. animation.datatype/ADTM_LOCATE                 animation.datatype/ADTM_LOCATE
  867.  
  868.     NAME
  869.         ADTM_LOCATE -- Locate a frame
  870.  
  871.     FUNCTION
  872.         ADTM_LOCATE locates a frame and displays it.
  873.  
  874.     RESULT
  875.         Returns non-zero on success,
  876.         0UL on failure.
  877.  
  878.     NOTE
  879.  
  880. animation.datatype/ADTM_PAUSE                   animation.datatype/ADTM_PAUSE
  881.  
  882.     NAME
  883.         ADTM_PAUSE -- Pause an animation playback
  884.  
  885.     FUNCTION
  886.         ADTM_PAUSE pauses an animation playback.
  887.         If the playback is currently active, it will be paused, then the
  888.         sound is turned off. The load process is turned off, too.
  889.  
  890.     RESULT
  891.         Non-zero if the playback has been turned off successfully.
  892.         0UL if on error (object is not attached to a window etc.).
  893.  
  894.     NOTE
  895.         - This method MUST be passes to the super-class (animation.datatype)
  896.           before the sub-class pauses !
  897.  
  898.         - Subclasses can treat this method like ADTM_STOP. Unlike
  899.           ADTM_STOP, a subclass should not reset any frame counter
  900.           (or Seek to any other file position, for example), because
  901.           in the most cases the playback starts again at this position.
  902.  
  903. animation.datatype/ADTM_START                   animation.datatype/ADTM_START
  904.  
  905.     NAME
  906.         ADTM_START -- Start animation playback
  907.  
  908.     FUNCTION
  909.         ADTM_START starts the animation playback.
  910.  
  911.         First the timer is reset to the current frame. If the load process
  912.         is inactive, it will be activated; this method waits until
  913.         a preload cycle is done.
  914.         Then the timer is activated and sound will be turned on.
  915.  
  916.         Starting with V41, this method is a NOP when the object is not
  917.         attached to a window/requester (this allows custom players
  918.         to use ADTM_START and the subclass optimisations made in a
  919.         ADTM_START / ADTM_STOP cycle).
  920.  
  921.     RESULT
  922.         Returns Non-Zero if playback has been started successfulls.
  923.         Returns 0UL on failure (e.g. objectnot attached to a window etc.)
  924.  
  925.     NOTE
  926.         - Subclasses can use ADTM_START to optimize playback. Starting
  927.           with ADTM_START and ADTM_PAUSE/ADTM_STOP, a continous range
  928.           of frames is read by the loading process.
  929.           A common example usage (in a subclass) is to send the first
  930.           read-packets (for the timstamp given in adtStart -> asa_Frame)
  931.           asyncrounous to the filesystem.
  932.           Don't wait for the packets ! ADTM_LOADFRAME should do this.
  933.  
  934.         - Subclasses must prepare for playback BEFORE passing
  935.           this msg to animation.datatype, because the loading process will
  936.           immediately start loading.
  937.  
  938.         - Subclasses MUST NOT hold any locks which are also locked in
  939.           ADTM_LOADFRAME / ADTM_UNLOADFRAME when passing ADTM_START to
  940.           animation.datatype. This causes a deadlock because the process
  941.           which is running ADTM_START will wait until the load process
  942.           has finished it's playback, but the load process is waiting
  943.           for the semaphore which is locked by the ADTM_START process.
  944.  
  945.         - Starting with V41, this method gurantees that the playback
  946.           has been started on exit.
  947.  
  948.         - Starting with V41, this method is safe when the object is
  949.           not attached to a window.
  950.  
  951. animation.datatype/ADTM_STOP                     animation.datatype/ADTM_STOP
  952.  
  953.     NAME
  954.         ADTM_STOP -- Stops an animation.datatype playback
  955.  
  956.     FUNCTION
  957.         ADTM_STOP stops an animation playback.
  958.         If the playback is currently active, it will be stopped, then the
  959.         sound is turned off. The load process is turned off, too.
  960.  
  961.     RESULT
  962.  
  963.     NOTE
  964.         - This method MUST be passes to the super-class (animation.datatype)
  965.           before the sub-class stops !
  966.  
  967.         - Starting with V41 this method gurantees that the playback has
  968.           been stopped on exit.
  969.  
  970. animation.datatype/DTM_COPY                       animation.datatype/DTM_COPY
  971.  
  972.     NAME
  973.         DTM_COPY -- Copy current frame to primary clipboard unit
  974.  
  975.     FUNCTION
  976.         DTM_COPY copies the current frame as an IFF ILBM frame to the
  977.         primary clipboard (unit 0).
  978.  
  979.         Starting with animation.datatype V41, this method creates a
  980.         temporary picture.datatype object, which will be fed with
  981.         bitmap, colormap, DTA_ObjName, DTA_ObjAuthor, DTA_ObjAnnotation,
  982.         DTA_ObjCopyright, DTA_ObjVersion, ADTA_BitMapHeader, ADTA_ModeID,
  983.         ADTA_NumColors, ADTA_ColorRegisters, ADTA_CRegs. Then this
  984.         method is passes to the picture.datatype object.
  985.  
  986.         Before V41, animation.datatype used it's own clipboard saving code.
  987.  
  988.     RESULT
  989.         The return code from the picture.datatype object.
  990.  
  991.     NOTE
  992.  
  993.     SEE ALSO
  994.         picture.datatype/DTM_COPY
  995.  
  996. animation.datatype/DTM_FRAMEBOX               animation.datatype/DTM_FRAMEBOX
  997.  
  998.     NAME
  999.         DTM_FRAMEBOX -- Get/or set the object's environment
  1000.  
  1001.     FUNCTION
  1002.         The DTM_FRAMEBOX method is used to set or get the object's
  1003.         environment.
  1004.  
  1005.         The FRAMEF_SPECIFY flag defines the mode of this method.
  1006.  
  1007.         If FRAMEF_SPECIFY is not set the object returns it's preferred
  1008.         (optimum) enviroment in dtf_FrameInfo (output).
  1009.  
  1010.         If FRAMEF_SPECIFY is set, the application tells the object
  1011.         about it's destination environment (got from dtf_ContentsInfo);
  1012.         animation.datatype does nothing here (NOP), but a subclass can use
  1013.         this to select a matching dither mode or select the best-matching
  1014.         stream (in multi-stream animations like MPEG-2).
  1015.  
  1016.     RESULT
  1017.         Returns non-zero for success, 0 for failure (NOP).
  1018.  
  1019.     NOTE
  1020.  
  1021. animation.datatype/DTM_PRINT                     animation.datatype/DTM_PRINT
  1022.  
  1023.     NAME
  1024.         DTM_PRINT -- Print current or specified frame to file.
  1025.  
  1026.     FUNCTION
  1027.         DTM_PRINT prints the current or a specifed frame as an IFF ILBM
  1028.         picture to the printer.
  1029.  
  1030.         Starting with animation.datatype V41, this method creates a
  1031.         temporary picture.datatype object, which will be fed with
  1032.         bitmap, colormap, DTA_ObjName, DTA_ObjAuthor, DTA_ObjAnnotation,
  1033.         DTA_ObjCopyright, DTA_ObjVersion, ADTA_BitMapHeader, ADTA_ModeID,
  1034.         ADTA_NumColors, ADTA_ColorRegisters, ADTA_CRegs. Then this
  1035.         method is passes to the picture.datatype object.
  1036.  
  1037.         Before V41, animation.datatype used it's own printer code.
  1038.  
  1039.     TAGS
  1040.         ADTA_Frame (ULONG) -- (V41) Timestamp of the frame to print.
  1041.             Defaults to the current frame.
  1042.  
  1043.         DTA_RastPort, DTA_DestCols, DTA_DestRows and DTA_Special
  1044.         are also recognised by the picture.datatype DTM_PRINT code.
  1045.         See picture.datatype/DTM_PRINT or datatypesclass autodoc.
  1046.  
  1047.     RESULT
  1048.         The return code from the picture.datatype object.
  1049.  
  1050.     BUGS
  1051.         - DTA_SelectDomain is ignored in V41 (as the whole DTM_SELECT
  1052.           code is not working yet).
  1053.  
  1054.     NOTE
  1055.  
  1056.     SEE ALSO
  1057.         picture.datatype/DTM_PRINT
  1058.  
  1059. animation.datatype/DTM_PROCLAYOUT           animation.datatype/DTM_PROCLAYOUT
  1060.  
  1061.     NAME
  1062.         DTM_PROCLAYOUT -- Layout an animation.datatype object on applications
  1063.                           process
  1064.  
  1065.     FUNCTION
  1066.         <not written yet, sorry>
  1067.  
  1068.     RESULT
  1069.  
  1070.     NOTE
  1071.  
  1072. animation.datatype/DTM_REMOVEDTOBJECT   animation.datatype/DTM_REMOVEDTOBJECT
  1073.  
  1074.     NAME
  1075.         DTM_REMOVEDTOBJECT -- Release all window/screen related resources
  1076.  
  1077.     FUNCTION
  1078.         DTM_REMOVEDTOBJECT is used to remove a animation.datatype object
  1079.         from screen context. The playback is stopped (using ADTM_STOP),
  1080.         then all resouces allocated in the initial GM_LAYOUT are freed.
  1081.         This includes shared or exclusive pens allocated, temporary bitmaps
  1082.         etc.
  1083.  
  1084.         After all, the method is passed to superclass.
  1085.  
  1086.         After using this method, the object is removed from screen's context
  1087.         and can be re-used in another screen.
  1088.  
  1089.     RESULT
  1090.         Returns return value from superclass.
  1091.  
  1092.     NOTE
  1093.         This method is normally invoked from within
  1094.         datatypes.library/RemoveDTObject. Manual usage is only neccesary
  1095.         where AddDTObject wasn't used (see embed.datatype for example).
  1096.  
  1097. animation.datatype/DTM_TRIGGER                 animation.datatype/DTM_TRIGGER
  1098.  
  1099.     NAME
  1100.         DTM_TRIGGER -- Trigger an action
  1101.  
  1102.     FUNCTION
  1103.         Trigger an asyncrounous (!) action on the object.
  1104.  
  1105.         Supported are:
  1106.  
  1107.         Label           | Command   | Function                | Parameters
  1108.         ----------------+-----------+-------------------------+------------
  1109.          "Pause"        | "PAUSE"   | STM_PAUSE               | STMD_VOID
  1110.          "Play"         | "PLAY"    | STM_PLAY                | STMD_VOID
  1111.          "Rewind",      | "REWIND"  | STM_REWIND              | STMD_VOID
  1112.          "Fast Forward" | "FF"      | STM_FASTFORWARD         | STMD_VOID
  1113.          "Stop"         | "STOP"    | STM_STOP                | STMD_VOID
  1114.          "Locate"       | "LOCATE"  | STM_LOCATE              | STMD_ULONG
  1115.  
  1116.         - Pause
  1117.           Pauses the current playback.
  1118.           The control process simply does a ADTM_PAUSE here.
  1119.  
  1120.         - Play
  1121.           Start playback
  1122.  
  1123.         - Rewind
  1124.           Skips ADTA_FrameIncrement frames back
  1125.  
  1126.         - Fast Forward
  1127.           Skips ADTA_FrameIncrement frames forward
  1128.  
  1129.         - Stop
  1130.           Stops the current playback.
  1131.           The control process simply does a ADTM_STOP here.
  1132.  
  1133.         - Locate
  1134.           The given parameter (dtt_Data; treated as ULONG) is used as the
  1135.           frame number (or timestamp) to locate (e.g. load and display this
  1136.           frame). This is simmilar to ADTM_LOCATE (but this isn't done here
  1137.           yet).
  1138.  
  1139.         Be sure to look at datatypes.library/GetDTTriggerMethodDataFlags to
  1140.         check whether a trigger method requires an argument or not !
  1141.  
  1142.     RESULT
  1143.         Returns non-zero for success,
  1144.         0 for failure (and result2 set to the cause:
  1145.         ERROR_NO_FREE_STORE          - no memory
  1146.         DTERROR_COULDNT_SEND_MESSAGE - object not ready to send (should NOT
  1147.                                        occur)
  1148.         ERROR_ACTION_NOT_KNOWN       - unknown STM_#? type
  1149.  
  1150.     BUGS
  1151.         - The given STM_#? type is not checked if it is supported or not.
  1152.  
  1153.     NOTE
  1154.         - Once again: This method is asyncrounous. You cannot assume
  1155.           that the triggered action is started nor finished after
  1156.           DTM_TRIGGER returns.
  1157.  
  1158.         - Common usage is a button field or a menu item to let the user
  1159.           to some actions on the object.
  1160.  
  1161.     SEE ALSO
  1162.         datatypes.library/GetDTTriggerMethodDataFlags
  1163.  
  1164. animation.datatype/DTM_WRITE                     animation.datatype/DTM_WRITE
  1165.  
  1166.     NAME
  1167.         DTM_WRITE -- Copy current or specified frame to file.
  1168.  
  1169.     FUNCTION
  1170.         DTM_WRITE copies the current or a specifed frame as an IFF ILBM
  1171.         picture to the given filehandle.
  1172.  
  1173.         Starting with animation.datatype V41, this method creates a
  1174.         temporary picture.datatype object, which will be fed with
  1175.         bitmap, colormap, DTA_ObjName, DTA_ObjAuthor, DTA_ObjAnnotation,
  1176.         DTA_ObjCopyright, DTA_ObjVersion, ADTA_BitMapHeader, ADTA_ModeID,
  1177.         ADTA_NumColors, ADTA_ColorRegisters, ADTA_CRegs. Then this
  1178.         method is passes to the picture.datatype object.
  1179.  
  1180.         Before V41, animation.datatype used it's own saving code.
  1181.  
  1182.     TAGS
  1183.         ADTA_Frame (ULONG) -- (V41) Timestamp of the frame to save.
  1184.             Defaults to the current frame.
  1185.  
  1186.     RESULT
  1187.         The return code from the picture.datatype object.
  1188.  
  1189.     NOTE
  1190.         - Subclasses may implement ADTA_Frame, ADTA_Frames and
  1191.           ADTA_FrameIncrement for their own encoders.
  1192.  
  1193.     SEE ALSO
  1194.         picture.datatype/DTM_WRITE
  1195.  
  1196. animation.datatype/GM_GOACTIVE                 animation.datatype/GM_GOACTIVE
  1197.  
  1198.     NAME
  1199.         GM_GOACTIVE -- Activate an animation.datatype gadget
  1200.  
  1201.     FUNCTION
  1202.         The GM_GOACTIVE method is used to indicate to a gadget that it has
  1203.         become active. This method overrides the superclass.
  1204.  
  1205.         See also GM_HANDLEINPUT, because this method is exactly the the
  1206.         same except the following things:
  1207.  
  1208.         - If the gpInput message mouse position is over the tapedeck.gadget
  1209.           it will become the active member (unless it has GA_Disabled == TRUE
  1210.           set for any reason).
  1211.  
  1212.     RESULT
  1213.         See GM_HANDLEINPUT
  1214.  
  1215.     NOTE
  1216.  
  1217. animation.datatype/GM_GOINACTIVE             animation.datatype/GM_GOINACTIVE
  1218.  
  1219.     NAME
  1220.         GM_GOINACTIVE -- Decativate an animation.datatype object
  1221.  
  1222.     FUNCTION
  1223.         The GM_GOINACTIBE method is used to indicate that the
  1224.         animation.datatype gadget has become inactive. This method overrides
  1225.         the superclass.
  1226.  
  1227.         If the embedded tapdeck.gadget was active, this method
  1228.         will be passed to it.
  1229.  
  1230.     RESULT
  1231.         The return code from the superclass is returned.
  1232.  
  1233.     NOTE
  1234.  
  1235. animation.datatype/GM_HANDLEINPUT           animation.datatype/GM_HANDLEINPUT
  1236.  
  1237.     NAME
  1238.         GM_HANDLEINPUT -- Process gadget input events
  1239.  
  1240.     FUNCTION
  1241.         The GM_HANDLEINPUT method is used to handle te input events of an
  1242.         active animation.datatype gadget. This method overrides the 
  1243.         superclass.
  1244.  
  1245.         If there is an active member (currently only tapedeck.gadget),
  1246.         all messages are passed througth to it.
  1247.  
  1248.         If there is no tapedeck.gadget in the display (e.g. DTA_ControlPanel
  1249.         == FALSE) and the object is not playing, a mouse SELECTUP starts
  1250.         the playback. If the object is playing, a SELECTUP pauses the
  1251.         playback.
  1252.  
  1253.     RESULT
  1254.         Do not interpret the results here, due they're a result of private
  1255.         internal activity.
  1256.         A later version will define here valid values.
  1257.  
  1258.     NOTE
  1259.  
  1260. animation.datatype/GM_HELPTEST                 animation.datatype/GM_HELPTEST
  1261.  
  1262.     NAME
  1263.         GM_HELPTEST -- Test if object has been hit by a help request
  1264.  
  1265.     FUNCTION
  1266.         The GM_HELPTEST method is used to determine if the given mouse
  1267.         coordinates are within the help domain of the animation.datatype
  1268.         gadget.
  1269.         This method overrides the superclass.
  1270.  
  1271.         If the mouse position is over the embedded tapdeck.gadget, this
  1272.         method is passed to it.
  1273.  
  1274.     RESULT
  1275.         GMR_HELPHIT or the return value of the embedded tapedeck.gadget
  1276.  
  1277.     NOTE
  1278.  
  1279. animation.datatype/GM_HITTEST                   animation.datatype/GM_HITTEST
  1280.  
  1281.     NAME
  1282.         GM_HITTEST -- Test if object has been hit by mouse
  1283.  
  1284.     FUNCTION
  1285.         The GM_HITTEST method is used to determine if the given mouse
  1286.         coordinates are within the domain of the animation.datatype gadget.
  1287.         This method overrides the superclass.
  1288.  
  1289.         If the mouse position is over the embedded tapdeck.gadget, this
  1290.         method is passed to it.
  1291.  
  1292.     RESULT
  1293.         GMR_GADGETHIT or the return value of the embedded tapedeck.gadget
  1294.  
  1295.     NOTE
  1296.  
  1297. animation.datatype/GM_LAYOUT                     animation.datatype/GM_LAYOUT
  1298.  
  1299.     NAME
  1300.         GM_LAYOUT -- Layout an animation.datatype object
  1301.  
  1302.     FUNCTION
  1303.         <not written yet, sorry>
  1304.  
  1305.     RESULT
  1306.         Returns return value from superclass.
  1307.  
  1308.     NOTE
  1309.  
  1310. animation.datatype/GM_RENDER                     animation.datatype/GM_RENDER
  1311.  
  1312.     NAME
  1313.         GM_RENDER -- Render an animation.datatype gadget
  1314.  
  1315.     FUNCTION
  1316.         The GM_RENDER method is used to render an animation.datatype object
  1317.         with the current frame. This method is also passed to the embedded
  1318.         tapedeck.gadget if DTA_ControlPanel is TRUE and if there is enougth
  1319.         space to render it (currenty a domain height < 16 pixels causes the
  1320.         tapedeck.gadget not to be rendered)
  1321. .       This method overrides the superclass.
  1322.  
  1323.         If this is the first GM_RENDER/GREDRAW_REDRAW after the initial
  1324.         GM_LAYOUT and DTA_Immediate was set to TRUE, the playback is
  1325.         started here.
  1326.  
  1327.     RESULT
  1328.         This method returns 0.
  1329.  
  1330.     NOTE
  1331.  
  1332. animation.datatype/MAIN                               animation.datatype/MAIN
  1333.  
  1334.     INTRODUCTION
  1335.         animation.datatype is the datatypes base class for all animation
  1336.         and movie subclasses. It is responsible for remapping, sound,
  1337.         scronisation, creating the controls and misc. other things
  1338.  
  1339.     FEATURES
  1340.         - Supports now the full animation.datatype interface like defined
  1341.           in include31:datatypes/animationclass.h:
  1342.           - Supports palette-per-frame, e.g. each frame can have it's own
  1343.             palette.
  1344.  
  1345.           - Dynamic timing. A frame can have a variable duration until
  1346.             the next frame occurs.
  1347.  
  1348.         - Fully compatible to the original animation.datatype V40.7
  1349.  
  1350.         - Configurable througth a preferences file.
  1351.  
  1352.         - Includes a CPU blitter for planar screens. If enabled by the prefs
  1353.           file, animation.datatype uses a CPU blitter instead of the OS
  1354.           blitter.
  1355.  
  1356.         - CyberGFX compatible:
  1357.           - Now animation.datatype V41 can handle non-planar bitmaps, e.g.
  1358.             chunkypixel bitmaps, as input.
  1359.             (Currently they cannot be remapped, the bitmaps are displayed
  1360.             unchanged on the destination screen).
  1361.  
  1362.           - Supports HAM/EHB -> 24-bit remapping. (TEMPORARY DISABLED).
  1363.  
  1364.         - No skipping anymore. The aniation.datatype V41 introduces
  1365.           a new feature called "adaptive frame rate selection". Instead
  1366.           of skipping frames when they cannot be displayed in real-time,
  1367.           the FPS rate is now adapted to fit (e.g. the maximum available
  1368.           playback speed without skipping).
  1369.  
  1370.  
  1371.     REQUIREMENTS
  1372.         - You need at least Kick/WB 3.0.
  1373.  
  1374.         - "realtime.library", >= V39              - for timing
  1375.         - "gadgets/tapedeck.gadget" (any version) - for the controls
  1376.  
  1377.            You need "sound.datatype" >= V40 for sound support.
  1378.  
  1379.     USAGE
  1380.         Usage is very simply: If you  have loaded an animation, you can
  1381.         control the animation using the tapedeck gadget at the bottom:
  1382.         "<<" skips some frames back
  1383.         ">"  starts playing
  1384.         ">>" skips some frames forward.
  1385.         The slider part can be used to move manually to a specific
  1386.         postion in the animation/movie.
  1387.  
  1388.         Note that there is also a prefs-file where you can set various
  1389.         options. See "preferences" section for details.
  1390.  
  1391.     INSTALLATION
  1392.         After unpacking this archive:
  1393.         Because this version does not include an Installer script, you have
  1394.         to do the installation manually through the shell:
  1395.  
  1396.           - Unpack this archive and copy the "animation.datatype" to
  1397.             SYS:Classes/DataTypes/:
  1398.  
  1399.             Copy CLONE FROM "animation.datatype" TO
  1400.             "SYS:Classes/DataTypes/animation.datatype"
  1401.  
  1402.     AUTHOR
  1403.         If you want to blame me, report any bugs, or wants a new version
  1404.         send your letter to:
  1405.                         Roland Mainz
  1406.                         Hohenstaufenstraße 8
  1407.                         52388 Nörvenich
  1408.                         GERMANY
  1409.  
  1410.         Phone: (+49)(0)2426/901568
  1411.         Fax:   (+49)(0)2426/901569
  1412.  
  1413.         EMAIL is also available (if you want to send me attachments
  1414.         larger than 1MB (up to 5MB, more with my permission):
  1415.  
  1416.         GISBURN@w-specht.rhein-ruhr.de
  1417.  
  1418.         Up to April 1998 I'm reachable using this email address, too:
  1419.         Reinhold.A.Mainz@KBV.DE
  1420.  
  1421.         | Please put your name and address in your mails !
  1422.         | German mailers should add their phone numbers.
  1423.         | See BUGS section above when submitting bug reports.
  1424.  
  1425.         Sorry, but I can only look once a week for mails.
  1426.         If you don't hear something from me within three weeks, please
  1427.         send your mail again (but watch about new releases) (problems with
  1428.         this email port are caused by reconfigurations, hackers, network
  1429.         problems etc.).
  1430.  
  1431.         The  entire  "animation.datatype"  package  may  be  noncommercially
  1432.         redistributed, provided  that  the package  is always  distributed
  1433.         in it's complete  form (including it's documentation). A small
  1434.         copy fee  for media costs is okay but any kind of commercial
  1435.         distribution is strictly forbidden without my permission !
  1436.         Comments and suggestions how to improve this program are
  1437.         generally appreciated!
  1438.  
  1439.         Thanks to: See "--datasheed--/THANKS TO" section...
  1440.  
  1441. animation.datatype/ObtainAnimationEnginemation.datatype/ObtainAnimationEngine
  1442.  
  1443.     NAME
  1444.         ObtainAnimationEngine -- Obtain the pointer to the animation class.
  1445.  
  1446.     SYNOPSIS
  1447.         class = ObtainAnimationEngine();
  1448.         d0
  1449.  
  1450.         struct IClass *ObtainAnimationEngine( void );
  1451.  
  1452.     FUNCTION
  1453.         This function is used to obtain the pointer to the class
  1454.         structure for this public BOOPSI class.
  1455.  
  1456.     RETURNS
  1457.         Returns a pointer to a valid public BOOPSI class pointer.
  1458.  
  1459.     NOTE
  1460.         - This function is also known as ObtainEngine. See
  1461.           "include31:clib/dtclass_protos.h"
  1462.  
  1463.         - Starting with V41, animation.datatype has a struct ClassLibrary
  1464.           structure (see V42 "include:intuition/classes.h") in it's
  1465.           classbase, where the BOOPSI class pointer can be obtained from.
  1466.           This method should be preferred over ObtainAnimationEngine.
  1467.  
  1468. animation.datatype/OM_DISPOSE                   animation.datatype/OM_DISPOSE
  1469.  
  1470.     NAME
  1471.         OM_DISPOSE -- Dispose aniation.datatype class instance
  1472.  
  1473.     FUNCTION
  1474.         This method disposed all animation.datatype instance related
  1475.         rousources, including the tapedeck.gadget, the player etc.
  1476.  
  1477.     RESULT
  1478.         Returns the return value of the superclass.
  1479.  
  1480.     NOTE
  1481.  
  1482. animation.datatype/OM_GET                           animation.datatype/OM_GET
  1483.  
  1484.     NAME
  1485.         OM_GET -- Get the value of an attribute
  1486.  
  1487.     FUNCTION
  1488.         The OM_GET method is used to get a value of an attribute.
  1489.  
  1490.         <not fully written yet, sorry>
  1491.  
  1492.         ADTA_DestFrame (struct BitMap *) (V41) -- current remapped frame
  1493.             (the matching palette can be found in ADTA_GRegs).
  1494.             Note that reading this attribute is only save when the object
  1495.             is NOT playing.
  1496.  
  1497.         ADTA_Sample (UBYTE *) (V41) -- current frame's sample.
  1498.             Note that reading this attribute is only safe when the object
  1499.             is NOT playing.
  1500.  
  1501.         ADTA_SampleLength (ULONG) (V41) -- current frame's sample length.
  1502.             Note that reading this attribute is only safe when the object
  1503.             is NOT playing.
  1504.  
  1505.         ADTA_Period (ULONG) (V41) -- current frame's sample period.
  1506.             Note that reading this attribute is only safe when the object
  1507.             is NOT playing.
  1508.  
  1509.         ADTA_Volume (ULONG) (V41) -- global volume.
  1510.  
  1511.         ADTA_Cycles (ULONG (V41) -- fixed to 1
  1512.  
  1513.     RESULT
  1514.         Returns non-zero on success, 0 on failure (attribute not recognized
  1515.         by OM_GET).
  1516.  
  1517.     NOTE
  1518.  
  1519. animation.datatype/OM_NEW                           animation.datatype/OM_NEW
  1520.  
  1521.     NAME
  1522.         OM_NEW -- Create a new animation.datatype object
  1523.  
  1524.     FUNCTION
  1525.         The OM_NEW method is used to create an instance of the
  1526.         animation.datatype class. This method is passed to the superclass
  1527.         first. After this, it sets up the instance data, creates sound
  1528.         and tapedeck objects, and the load and display processes. After
  1529.         all, when the object and the embedded objects and threads are
  1530.         ready for action, this method returns.
  1531.  
  1532.         On error this method calls OM_DISPOSE for it's own instance
  1533.         (e.g. CoerceMethod( cl, (Object *)retval, OM_DISPOSE );) and
  1534.         returns an error code.
  1535.  
  1536.     RESULT
  1537.         On success, a ptr to the object is returned,
  1538.         on failure, 0UL is returned, Result2 (IoErr()) contains the
  1539.         cause.
  1540.  
  1541.     NOTE
  1542.  
  1543. animation.datatype/OM_SET                           animation.datatype/OM_SET
  1544.  
  1545.     NAME
  1546.         OM_SET -- Set the attributes of a animation.datatype object
  1547.  
  1548.     FUNCTION
  1549.         The OM_SET method is used to set the attributes of a
  1550.         animation.datatype gadget. This method is passed to the superclass
  1551.         first.
  1552.  
  1553.     TAGS
  1554.         <not complety written yet, sorry>
  1555.  
  1556.         DTA_TopVert (LONG) -- Used to specify the vertical top image
  1557.             position. The value is stored in
  1558.             struct DTSpecialInfo -> si_TopVert. Values < 0 are set to 0.
  1559.             Setting this value causes that the object returns non-zero
  1560.             for OM_SET/OM_UPDATE, which should trigger an GM_RENDER with
  1561.             GREDRAW_UPDATE (the topmost instance is responsible for doing
  1562.             this).
  1563.             This overrides superclass's functionality.
  1564.  
  1565.         DTA_TopHoriz (LONG) -- Used to specify the horizontal top image
  1566.             position. The value is stored in
  1567.             struct DTSpecialInfo -> si_TopHoriz. Values < 0 are set to 0.
  1568.             Setting this value causes that the object returns non-zero
  1569.             for OM_SET/OM_UPDATE, which should trigger an GM_RENDER with
  1570.             GREDRAW_UPDATE (the topmost instance is responsible for doing
  1571.             this).
  1572.             This overrides superclass's functionality.
  1573.  
  1574.         ADTA_Remap (BOOL) -- Indicate whether the picture should be
  1575.             remapped or not.
  1576.             ADTA_Remap == TRUE does only work if DTM_FRAMEBOX sets the
  1577.             FIF_REMAPABLE flag to indicate that animation.datatype
  1578.             can remap the incoming data.
  1579.             WARNING: This tag MUST not be changed while the object is
  1580.             attached to a window or requester !
  1581.  
  1582.             Applicability is (ISGU).
  1583.  
  1584.     RESULT
  1585.         Non-zero if a GM_RENDER with GREDRAW_UPDATE should be triggered
  1586.         by the topmost class.
  1587.  
  1588.     NOTE
  1589.  
  1590.     SEE ALSO
  1591.         OM_UPDATE, OM_NEW
  1592.  
  1593. animation.datatype/OM_UPDATE                     animation.datatype/OM_UPDATE
  1594.  
  1595.     NAME
  1596.         OM_UPDATE -- Update attributes
  1597.  
  1598.     FUNCTION
  1599.         OM_UPDATE updates anmation.datatype attributes, see OM_SET for
  1600.         details.
  1601.  
  1602.     TAGS
  1603.         See OM_SET autodoc.
  1604.  
  1605.     RESULT
  1606.  
  1607.     NOTE
  1608.  
  1609.     SEE ALSO
  1610.         OM_SET, OM_NEW
  1611.  
  1612. animation.datatype/preferences                 animation.datatype/preferences
  1613.  
  1614.    NAME
  1615.        preferences
  1616.  
  1617.    DESCRIPTION
  1618.        The "ENV:Classes/DataTypes/animation.prefs" file contains global
  1619.        settings for the animation datatype.
  1620.        The preferences file is an ASCII file containing one line where the
  1621.        preferences can be set.
  1622.        It can be superset by a local variable with the same name.
  1623.  
  1624.        Each line can contain settings, special settings for some subclasses
  1625.        can be set using the MATCHCLASS option.
  1626.        Lines beginning with a '#' or ';' chars are treated as comments.
  1627.        Lines are limitted to 256 chars.
  1628.  
  1629.    TEMPLATE
  1630.        MATCHCLASS/K,VERBOSE/S,ADAPTIVEFPS/S,NOADAPTIVEFPS/S,
  1631.        NUMPREFETCHFRAMES/K/N,WAITBOVP/S,NOWAITBOVP/S,OSBLITTER/S,
  1632.        CPUBLITTER/S,CHOOSEBLITTER/S,SHARECHIP/S,NOSHARECHIP/S,HACKS/S,
  1633.        NOHACKS/S
  1634.  
  1635.        MATCHCLASS -- Public class name. If given, the current prefs line
  1636.            is only for this subclass only.
  1637.            Example: MATCHCLASS="cdxl.datatype"
  1638.  
  1639.        VERBOSE -- Print information about the animation.
  1640.  
  1641.        ADAPTIVEFPS -- If set, the animation.datatype recalculates the
  1642.            playback rate that all frames and sounds can be displayed without
  1643.            skipping.
  1644.            This option is on per default starting with animation.datatype V41
  1645.  
  1646.        NOADAPTIVEFPS -- Turns the ADAPTIVEFPS flag off.
  1647.  
  1648.        NUMPREFETCHFRAMES -- Increases the number of frams which should
  1649.            be pre-fetched by the load process.
  1650.            Note: Increasing this value may cause the animation to run more
  1651.            smoothly, but takes also more memory.
  1652.            Defaults to 10.
  1653.  
  1654.        WAITBOVP -- Wait until raster beam reaches the bottom of the current
  1655.            viewport (screen). Only useful with some Gfx-Card-Software
  1656.            or graphics.library > V40.
  1657.            (In the future this option should be enabled if CyberGFX >= V41
  1658.            is detected).
  1659.  
  1660.        NOWAITBOVP -- Turns WAITBOVP flag off.
  1661.  
  1662.        OSBLITTER -- Use OS blitter even on planar screens. It is
  1663.            mutually exclusive to CPUBLITTER and CHOOSEBLITTER options.
  1664.            This option is off per default.
  1665.  
  1666.        CPUBLITTER - Use CPU blitter on planar screens. It is
  1667.            mutually exclusive to OSBLITTER and CHOOSEBLITTER options.
  1668.            This option is off per default.
  1669.  
  1670.        CHOOSEBLITTER -- If destination is a planar screen, the datatype
  1671.            makes a speed comparisation whether CPU or OS blitter is faster.
  1672.            It is mutually exclusive to OSBLITTER and CPUBLITTER options.
  1673.            This option is on per default.
  1674.  
  1675.        SHARECHIP -- animation.datatype <= V41.5 tests incoming planar
  1676.            bitmaps if they're in chipmem (using TypeOfMem) or not; if
  1677.            they're in chipmem and there's no remapping required, they're
  1678.            passed througth to BltBitMap rastport directly instead of
  1679.            copy'ing them to a chipmem buffer and blit from there.
  1680.            Using this option the TypeOfMem test can be turned on again,
  1681.            which may be usefull for high-speed animations (> 30 fps) on
  1682.            an own MultiView screen using the Amiga native screen modes.
  1683.            This option is off per default.
  1684.  
  1685.        NOSHARECHIP -- Turns the SHARECHIP option off.
  1686.            This option is on per default.
  1687.  
  1688.        HACKS -- Use some internal hacks (system-conform, but I don't
  1689.            like them).
  1690.            This option is on per default.
  1691.  
  1692.        NOHACKS -- Turns HACKS option off.
  1693.  
  1694.    NOTE
  1695.        An invalid prefs file line will be ignored and forces the VERBOSE
  1696.        output.
  1697.  
  1698.    BUGS
  1699.        - Low memory may cause that the prefs file won't be parsed.
  1700.  
  1701.        - Lines are limitted to 256 chars
  1702.  
  1703.        - An invalid prefs file line will be ignored.
  1704.  
  1705.        - The sample path length is limitted to 200 chars. A larger
  1706.          value may crash the machine if an error occurs.
  1707.  
  1708.